<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>Using Custom Tags - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level3"><a href="bnagy.html">What Is a JSP Page?</a></p>
<p class="toc level4"><a href="bnagy.html#bnagz">A Simple JSP Page Example</a></p>
<p class="toc level3 tocsp"><a href="bnahb.html">The Example JSP Pages</a></p>
<p class="toc level3"><a href="bnahe.html">The Life Cycle of a JSP Page</a></p>
<p class="toc level4"><a href="bnahe.html#bnahf">Translation and Compilation</a></p>
<p class="toc level4"><a href="bnahe.html#bnahg">Execution</a></p>
<p class="toc level5"><a href="bnahe.html#bnahh">Buffering</a></p>
<p class="toc level5"><a href="bnahe.html#bnahi">Handling JSP Page Errors</a></p>
<p class="toc level3 tocsp"><a href="bnahj.html">Creating Static Content</a></p>
<p class="toc level4"><a href="bnahj.html#bnahk">Response and Page Encoding</a></p>
<p class="toc level3 tocsp"><a href="bnahl.html">Creating Dynamic Content</a></p>
<p class="toc level4"><a href="bnahl.html#bnahm">Using Objects within JSP Pages</a></p>
<p class="toc level5"><a href="bnahl.html#bnahn">Using Implicit Objects</a></p>
<p class="toc level5"><a href="bnahl.html#bnaho">Using Application-Specific Objects</a></p>
<p class="toc level5"><a href="bnahl.html#bnahp">Using Shared Objects</a></p>
<p class="toc level3 tocsp"><a href="bnahq.html">Unified Expression Language</a></p>
<p class="toc level4"><a href="bnahq.html#bnahr">Immediate and Deferred Evaluation Syntax</a></p>
<p class="toc level5"><a href="bnahq.html#bnahs">Immediate Evaluation</a></p>
<p class="toc level5"><a href="bnahq.html#bnaht">Deferred Evaluation</a></p>
<p class="toc level4 tocsp"><a href="bnahq.html#bnahu">Value and Method Expressions</a></p>
<p class="toc level5"><a href="bnahq.html#bnahv">Value Expressions</a></p>
<p class="toc level5"><a href="bnahq.html#bnahz">Method Expressions</a></p>
<p class="toc level4 tocsp"><a href="bnahq.html#bnaia">Defining a Tag Attribute Type</a></p>
<p class="toc level4"><a href="bnahq.html#bnaic">Deactivating Expression Evaluation</a></p>
<p class="toc level4"><a href="bnahq.html#bnaid">Literal Expressions</a></p>
<p class="toc level4"><a href="bnahq.html#bnaif">Resolving Expressions</a></p>
<p class="toc level5"><a href="bnahq.html#bnaig">Process of Expression Evaluation</a></p>
<p class="toc level5"><a href="bnahq.html#bnaih">EL Resolvers</a></p>
<p class="toc level4 tocsp"><a href="bnahq.html#bnaij">Implicit Objects</a></p>
<p class="toc level4"><a href="bnahq.html#bnaik">Operators</a></p>
<p class="toc level4"><a href="bnahq.html#bnail">Reserved Words</a></p>
<p class="toc level4"><a href="bnahq.html#bnaim">Examples of EL Expressions</a></p>
<p class="toc level4"><a href="bnahq.html#bnaio">Functions</a></p>
<p class="toc level5"><a href="bnahq.html#bnaip">Using Functions</a></p>
<p class="toc level5"><a href="bnahq.html#bnaiq">Defining Functions</a></p>
<p class="toc level3 tocsp"><a href="bnair.html">JavaBeans Components</a></p>
<p class="toc level4"><a href="bnair.html#bnais">JavaBeans Component Design Conventions</a></p>
<p class="toc level4"><a href="bnair.html#bnait">Creating and Using a JavaBeans Component</a></p>
<p class="toc level4"><a href="bnair.html#bnaiu">Setting JavaBeans Component Properties</a></p>
<p class="toc level4"><a href="bnair.html#bnaix">Retrieving JavaBeans Component Properties</a></p>
<div class="onpage">
<p class="toc level3 tocsp"><a href="">Using Custom Tags</a></p>
<p class="toc level4"><a href="#bnaiz">Declaring Tag Libraries</a></p>
<p class="toc level4"><a href="#bnaja">Including the Tag Library Implementation</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnajb.html">Reusing Content in JSP Pages</a></p>
<p class="toc level3"><a href="bnajc.html">Transferring Control to Another Web Component</a></p>
<p class="toc level4"><a href="bnajc.html#bnajd"><tt>jsp:param</tt> Element</a></p>
<p class="toc level3 tocsp"><a href="bnaje.html">Including an Applet</a></p>
<p class="toc level3"><a href="bnajg.html">Setting Properties for Groups of JSP Pages</a></p>
<p class="toc level4"><a href="bnajg.html#bnajh">Deactivating EL Expression Evaluation</a></p>
<p class="toc level5"><a href="bnajg.html#bnajk">Declaring Page Encodings</a></p>
<p class="toc level5"><a href="bnajg.html#bnajl">Defining Implicit Includes</a></p>
<p class="toc level5"><a href="bnajg.html#bnajm">Eliminating Extra White Space</a></p>
<p class="toc level3 tocsp"><a href="bnajn.html">Further Information about JavaServer Pages Technology</a></p>
<p class="toc level2 tocsp"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level2"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnair.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnajb.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnaiy"></a><h3>Using Custom Tags</h3>
<p><b>Custom tags</b> are user-defined JSP language elements that encapsulate recurring tasks. Custom tags are
distributed in a <b>tag library</b>, which defines a set of related custom tags
and contains the objects that implement the tags.</p><p>Custom tags have the syntax</p><pre>&lt;prefix:tag attr1="value" ... attrN="value" /></pre><p>or</p><pre>&lt;prefix:tag attr1="value" ... attrN="value" >
     <i>body</i>&lt;/prefix:tag></pre><p>where <tt>prefix</tt> distinguishes tags for a library, <tt>tag</tt> is the tag identifier,
and <tt>attr1 ... attrN</tt> are attributes that modify the behavior of the tag.</p><p><a name="indexterm-390"></a>To use a custom tag in a JSP page, you must</p>
<ul><li><p>Declare the tag library containing the tag</p></li>
<li><p>Make the tag library implementation available to the web application</p></li></ul>
<p>See <a href="bnalj.html">Chapter&nbsp;8, Custom Tags in JSP Pages</a> for detailed information on the different types of tags and how
to implement tags.</p>

<a name="bnaiz"></a><h4>Declaring Tag Libraries</h4>
<p><a name="indexterm-391"></a><a name="indexterm-392"></a>To declare that a JSP page will use tags defined in a
tag library, you include a <tt>taglib</tt> directive in the page before any custom tag
from that tag library is used. If you forget to include the
<tt>taglib</tt> directive for a tag library in a JSP page, the JSP compiler
will treat any invocation of a custom tag from that library as static
data and will simply insert the text of the custom tag call into
the response.</p><pre>&lt;%@ taglib prefix="tt" [tagdir=/WEB-INF/tags/<i>dir</i> | uri=<i>URI</i> ] %></pre><p>The <tt>prefix</tt> attribute defines the prefix that distinguishes tags defined by a given
tag library from those provided by other tag libraries.</p><p>If the tag library is defined with tag files (see <a href="bnama.html">Encapsulating Reusable Content Using Tag Files</a>), you
supply the <tt>tagdir</tt> attribute to identify the location of the files. The
value of the attribute must start with <tt>/WEB-INF/tags/</tt>. A translation error will occur if
the value points to a directory that doesn&rsquo;t exist or if it is
used in conjunction with the <tt>uri</tt> attribute.</p><p>The <tt>uri</tt> attribute refers to a URI that uniquely identifies the tag library
descriptor (TLD), a document that describes the tag library (see <a href="bnamu.html">Tag Library Descriptors</a>).</p><p><a name="indexterm-393"></a>Tag library descriptor file names must have the extension <tt>.tld</tt>. TLD files
are stored in the <tt>WEB-INF</tt> directory or subdirectory of the WAR file, or
in the <tt>META-INF</tt> directory or subdirectory of a tag library packaged in a
JAR. You can reference a TLD directly or indirectly.</p><p><a name="indexterm-394"></a>The following <tt>taglib</tt> directive directly references a TLD file name:</p><pre>&lt;%@ taglib prefix="tlt" uri="/WEB-INF/iterator.tld"%></pre><p><a name="indexterm-395"></a>This <tt>taglib</tt> directive uses a short logical name to indirectly reference the TLD:</p><pre>&lt;%@ taglib prefix="tlt" uri="/tlt"%></pre><p>The <tt>iterator</tt> example defines and uses a simple iteration tag. The JSP pages
use a logical name to reference the TLD.</p><p>To deploy and run the <tt>iterator</tt> application with NetBeans IDE, follow these steps:</p>
<ol><li><p>In NetBeans IDE, select File&rarr;Open Project.</p></li>
<li><p>In the Open Project dialog, navigate to:</p><pre><i>tut-install</i>/javaeetutorial5/examples/web/</pre></li>
<li><p>Select the <tt>iterator</tt> folder.</p></li>
<li><p>Select the Open as Main Project check box.</p></li>
<li><p>Click Open Project.</p></li>
<li><p>In the Projects tab, right-click the <tt>iterator</tt> project, and select Undeploy and Deploy.</p></li>
<li><p>To run the application, open the bookstore URL <tt>http://localhost:8080/iterator</tt>.</p></li></ol>
<p>To deploy and run the <tt>iterator</tt> application with Ant, follow these steps:</p>
<ol><li><p>In a terminal window, go to <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/web/iterator/</tt>.</p></li>
<li><p>Type <tt><b>ant</b></tt>. This command will spawn any necessary compilations, copy files to the <tt></tt><i>tut-install</i><tt>/javaeetutorial5/examples/web/iterator/build/</tt> directory, and create a WAR file.</p></li>
<li><p>Start the Application Server.</p></li>
<li><p>Type <tt><b>ant deploy</b></tt>.</p></li>
<li><p>To run the example, open your browser to <tt>http://localhost:8080/iterator</tt>.</p></li></ol>
<p>To learn how to configure the example, refer to the deployment descriptor, which
includes the following configurations:</p>
<ul><li><p>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</p></li>
<li><p>Nested inside a <tt>jsp-config</tt> element is a <tt>taglib</tt> element, which provides information on a tag library used by the pages of the application. Inside the <tt>taglib</tt> element are the <tt>taglib-uri</tt> element and the <tt>taglib-location</tt> element. The <tt>taglib-uri</tt> element identifies the logical name of the tag library. The <tt>taglib-location</tt> element gives the absolute location or the absolute URI of the tag library.</p></li></ul>
<p>The absolute URIs for the JSTL library are as follows:</p>
<ul><li><p><b>Core</b>: <a href="http://java.sun.com/jsp/jstl/core">http://java.sun.com/jsp/jstl/core</a></p></li>
<li><p><b>XML</b>: <a href="http://java.sun.com/jsp/jstl/xml">http://java.sun.com/jsp/jstl/xml</a></p></li>
<li><p><b>Internationalization</b>: <a href="http://java.sun.com/jsp/jstl/fmt">http://java.sun.com/jsp/jstl/fmt</a></p></li>
<li><p><b>SQL</b>: <a href="http://java.sun.com/jsp/jstl/sql">http://java.sun.com/jsp/jstl/sql</a></p></li>
<li><p><b>Functions</b>: <a href="http://java.sun.com/jsp/jstl/functions">http://java.sun.com/jsp/jstl/functions</a></p></li></ul>
<p><a name="indexterm-396"></a>When you reference a tag library with an absolute URI that exactly matches
the URI declared in the <tt>taglib</tt> element of the TLD (see <a href="bnamu.html">Tag Library Descriptors</a>), you do
not have to add the <tt>taglib</tt> element to <tt>web.xml</tt>; the JSP container
automatically locates the TLD inside the JSTL library implementation.</p>

<a name="bnaja"></a><h4>Including the Tag Library Implementation</h4>
<p><a name="indexterm-397"></a><a name="indexterm-398"></a>In addition to declaring the tag library, you also must make the tag
library implementation available to the web application. There are several ways to do
this. Tag library implementations can be included in a WAR in an unpacked
format: Tag files are packaged in the <tt>/WEB-INF/tag/</tt> directory, and tag handler classes
are packaged in the <tt>/WEB-INF/classes/</tt> directory of the WAR. Tag libraries already packaged
into a JAR file are included in the <tt>/WEB-INF/lib/</tt> directory of the WAR.
Finally, an application server can load a tag library into all the web
applications running on the server. For example, in the Application Server, the JSTL
TLDs and libraries are distributed in the archive <tt>appserv-jstl.jar</tt> in <tt></tt><i>as-install</i><tt>/lib/</tt>. This library
is automatically loaded into the classpath of all web applications running on the
Application Server, so you don&rsquo;t need to add it to your web application.</p><p>The <tt>iterator</tt> tag library is implemented with tag handlers. Therefore, its implementation classes
are packaged in the <tt>/WEB-INF/classes/</tt> directory.</p>
         </div>
         <div class="navigation">
             <a href="bnair.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnajb.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

